fix: resolve flash of unstyled content in dark mode by TusharThakur04 · Pull Request #766 · nodejs/doc-kit

TusharThakur04 · 2026-04-13T14:23:51Z

Description

This PR resolves the FOUC by resolving system to dark or light using matchMedia.
Earlier system was directly being applied as set-theme = system

Validation

before :

Screencast.from.2026-04-13.19-26-34.webm

after :

Screencast.from.2026-04-13.19-24-03.webm

Related Issues

n/a

Check List

I have read the Contributing Guidelines and made commit messages that follow the guideline.
I have run node --run test and all tests passed.
I have check code formatting with node --run format & node --run lint.
I've covered new added functionality with unit tests if necessary.

cursor · 2026-04-13T14:23:59Z

PR Summary

Low Risk
Low risk: changes are limited to how the initial data-theme is computed and inlined before first paint; main risk is edge-case behavior differences for users with stored theme preferences.

Overview
Fixes initial-page theme application to avoid dark-mode Flash of Unstyled Content by replacing the hardcoded inline snippet with an injected themeScript.

Adds ui/theme-script.mjs, which resolves the stored theme preference (including system) to a concrete dark/light value via matchMedia and applies it to documentElement before render; processing.mjs now passes this script into template.html for inlining.

^{Reviewed by Cursor Bugbot for commit ae47eff. Bugbot is set up for automated code reviews on this repo. Configure here.}

vercel · 2026-04-13T14:24:12Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Apr 25, 2026 5:43pm

canerakdas · 2026-04-15T09:25:35Z


  <!-- Apply theme before paint to avoid Flash of Unstyled Content -->
-  <script>document.documentElement.setAttribute("data-theme", document.documentElement.style.colorScheme = localStorage.getItem("theme") || (matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light"));</script>
+  <script>(function(){var p=localStorage.getItem("theme");var t=(!p||p==="system")?(matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light"):p;document.documentElement.setAttribute("data-theme",t);document.documentElement.style.colorScheme=t;})();</script>


I think we should make this code block more readable for developers who want to contribute or review it. Instead of writing it as a single line, using more descriptive variable names shouldn't significantly impact the file size. @nodejs/web-infra WDYT?

If that's the case this script source should be in its own file and then inlined via a template string {{}}

avivkeller · 2026-04-15T20:09:47Z

This seems highly complex

TusharThakur04 · 2026-04-15T20:27:06Z

the {$themeScript} literal is being replaced by newly created themeScript by generate.mjs

it is done so that the script is available before rendering the html and there is no latency which could have happened if browser makes request for the themeScript.mjs if we use src inside the script tag

ovflowd · 2026-04-16T10:27:56Z

+
+  // Wrap theme script in script tag and replace the placeholder
+  const inlinedThemeScript = `<script>${themeScriptContent}</script>`;
+  template = template.replace('${themeScript}', inlinedThemeScript);


Don't use .replace(), I believe that @avivkeller implemented a system to automatically evaluate such template variables?

ovflowd · 2026-04-16T10:28:13Z

+  It injects an inline script that initializes the theme (light/dark)
+  before the page renders to avoid Flash of Unstyled Content (FOUC).
+-->
+  ${themeScript}


Suggested change

${themeScript}

<script type="javascript">${themeScript}</script>

ovflowd · 2026-04-16T10:28:21Z


-  <!-- Apply theme before paint to avoid Flash of Unstyled Content -->
-  <script>document.documentElement.setAttribute("data-theme", document.documentElement.style.colorScheme = localStorage.getItem("theme") || (matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light"));</script>
+<!--


No need for this comment.

ovflowd · 2026-04-16T10:28:53Z

+
+  // Read the theme script from UI folder
+  const themeScriptPath = join(import.meta.dirname, 'ui', 'theme-script.mjs');
+  const themeScriptContent = await readFile(themeScriptPath, 'utf-8');


We shouldn't ue fs the idea is to use our rolldown pipeline for this script, so it gets properly minified and transformed.

Otherwise the file doesn't get minified, which is the idea behind separating src<>final result.

codecov · 2026-04-18T13:30:06Z

Codecov Report

❌ Patch coverage is 50.00000% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 77.94%. Comparing base (3d00fa8) to head (ae47eff).
⚠️ Report is 9 commits behind head on main.

Files with missing lines	Patch %	Lines
src/generators/web/utils/processing.mjs	50.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #766      +/-   ##
==========================================
- Coverage   78.43%   77.94%   -0.49%     
==========================================
  Files         157      159       +2     
  Lines       13962    14058      +96     
  Branches     1152     1152              
==========================================
+ Hits        10951    10958       +7     
- Misses       3006     3095      +89     
  Partials        5        5

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3c1f1be. Configure here.}

TusharThakur04 · 2026-04-21T14:50:12Z

@ovflowd
please review, i ve made the changes you suggested

avivkeller · 2026-04-22T13:04:47Z

+'use strict';
+
+/**
+ * This script is designed to be inlined in the <head> of the HTML template.
+ * It must execute BEFORE the body renders to prevent a Flash of Unstyled Content (FOUC).
+ */
+
+export default `(function initializeTheme() {
+  const THEME_STORAGE_KEY = 'theme';
+  const THEME_DATA_ATTRIBUTE = 'data-theme';
+  const DARK_QUERY = '(prefers-color-scheme: dark)';
+
+  const savedUserPreference = localStorage.getItem(THEME_STORAGE_KEY);
+  const systemSupportsDarkMode = window.matchMedia(DARK_QUERY).matches;
+
+  const shouldApplyDark =
+    savedUserPreference === 'dark' ||
+    (savedUserPreference === 'system' && systemSupportsDarkMode) ||
+    (!savedUserPreference && systemSupportsDarkMode);
+
+  const themeToApply = shouldApplyDark ? 'dark' : 'light';
+
+  document.documentElement.setAttribute(THEME_DATA_ATTRIBUTE, themeToApply);
+  document.documentElement.style.colorScheme = themeToApply;
+})();`.trim();


If we do go with the "custom script file" way, we should import with fs and not a string

#766 (comment)

canerakdas · 2026-04-25T17:38:01Z

+ * It must execute BEFORE the body renders to prevent a Flash of Unstyled Content (FOUC).
+ */
+function initializeTheme() {
+  const THEME_STORAGE_KEY = 'theme';


Even though const is widely available, since this scripts will run directly in the browser, it’s safer to keep it as var

canerakdas

LGTM, I just left one comment 🚀

TusharThakur04 requested a review from a team as a code owner April 13, 2026 14:23

vercel Bot deployed to Preview April 13, 2026 14:25 View deployment

cursor Bot reviewed Apr 13, 2026

View reviewed changes

Comment thread src/generators/web/template.html Outdated

TusharThakur04 force-pushed the fix/dark-mode-FOUC branch from 893ddea to 4ae89b4 Compare April 13, 2026 14:29

vercel Bot deployed to Preview April 13, 2026 14:30 View deployment

canerakdas reviewed Apr 15, 2026

View reviewed changes

TusharThakur04 force-pushed the fix/dark-mode-FOUC branch from 4ae89b4 to 34de276 Compare April 15, 2026 18:12

vercel Bot deployed to Preview April 15, 2026 18:12 View deployment

TusharThakur04 requested review from canerakdas and ovflowd April 15, 2026 18:18

ovflowd reviewed Apr 16, 2026

View reviewed changes

TusharThakur04 force-pushed the fix/dark-mode-FOUC branch from 34de276 to 0b53971 Compare April 18, 2026 13:29

TusharThakur04 requested a review from ovflowd April 18, 2026 13:29

vercel Bot deployed to Preview April 18, 2026 13:30 View deployment

cursor Bot reviewed Apr 18, 2026

View reviewed changes

Comment thread src/generators/web/utils/processing.mjs Outdated

TusharThakur04 force-pushed the fix/dark-mode-FOUC branch from 0b53971 to 3c1f1be Compare April 18, 2026 13:43

vercel Bot deployed to Preview April 18, 2026 13:43 View deployment

cursor Bot reviewed Apr 18, 2026

View reviewed changes

Comment thread src/generators/web/ui/theme-script.mjs Outdated

TusharThakur04 force-pushed the fix/dark-mode-FOUC branch from 3c1f1be to 501c20b Compare April 18, 2026 14:27

vercel Bot deployed to Preview April 18, 2026 14:28 View deployment

avivkeller reviewed Apr 22, 2026

View reviewed changes

canerakdas reviewed Apr 24, 2026

View reviewed changes

Comment thread src/generators/web/ui/theme-script.mjs Outdated

TusharThakur04 force-pushed the fix/dark-mode-FOUC branch from 501c20b to 667b443 Compare April 24, 2026 22:58

vercel Bot deployed to Preview April 24, 2026 22:59 View deployment

TusharThakur04 requested a review from canerakdas April 24, 2026 23:00

canerakdas reviewed Apr 25, 2026

View reviewed changes

fix: resolve flash of unstyled content (FOUC) in dark mode

ae47eff

canerakdas approved these changes Apr 25, 2026

View reviewed changes

TusharThakur04 force-pushed the fix/dark-mode-FOUC branch from 667b443 to ae47eff Compare April 25, 2026 17:42

vercel Bot deployed to Preview April 25, 2026 17:43 View deployment

	${themeScript}
	<script type="javascript">${themeScript}</script>

Conversation

TusharThakur04 commented Apr 13, 2026

Description

Validation

before :

after :

Related Issues

Check List

Uh oh!

cursor Bot commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

vercel Bot commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

avivkeller commented Apr 15, 2026

Uh oh!

TusharThakur04 commented Apr 15, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov Bot commented Apr 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

TusharThakur04 commented Apr 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

canerakdas left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

cursor Bot commented Apr 13, 2026 •

edited

Loading

vercel Bot commented Apr 13, 2026 •

edited

Loading

codecov Bot commented Apr 18, 2026 •

edited

Loading